/*********************************************************************
 *
 *              Application Programming Interface (API) 
 *                     for COM-R04-S01b Module
 *
 *********************************************************************
 * FileName:        com_r04_s01b.h
 * Dependencies:    platform.h
 * Processor:       processor independent
 * Complier:        compiler independent              
 * Company:         Budapest University of Technology and Economics
 * 					Department of Measurement and Information Systems
 * 
 * note:
 *	General API for the COM-R04-S01b Mitmot module. This API use the
 * 	Mitmote BUS functions specified by the mcu API.
 * 
 *  Standard COM-R04-S01b is configured to 433MHz operation with 10MHz
 *  xtal using a 12pF load. Also as typically is FIFO enabled operation
 *  only mitmot GPIO13 and GPIO14 is used in addition to the SPI pins.
 *  GPIO13 is for SPI slave select, and GPIO14 for the Interrupt signal
 *  (nIRQ) 
 * 
 * Author               Date    Comment
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Balazs Scherer     10/06/05   Original
 ********************************************************************/
 
#ifndef _COM_R04_S01b_H_
#define _COM_R04_S01b_H_

#include "platform.h"

/*********************************************************************/
/*********************************************************************/
/**********          ERROR definitions      	      ****************/
/*********************************************************************/
/*********************************************************************/

#define COM_R04_S01__TIMEOUT	2
#define COM_R04_S01__ERROR		1
#define COM_R04_S01__NOERROR	0


/*********************************************************************/
/*********************************************************************/
/**********          Inicialisation, controll	      ****************/
/*********************************************************************/
/*********************************************************************/

/*********************************************************************
 * Function: 	  void com_r04_s01__Init_433 (void)        
 *
 * PreCondition:  none  
 *     
 * Input:         unsigned int sub_frequency: The sub frequency band for RF 
 * 					communication. 
 * 				  unsigned char baseband_bw: Select the baseband BW
 * 					between 67kHz and 400 kHz
 * 				  unsigned char deviation: FSK deviation between 15kHz to 240 kHz 
 * 				  unsigned char power: Relative output power. The maximum is about 8dBm
 * 				  unsigned char data_rate: setting the communication data rate
 *
 * Output:        none  
 *
 * Side Effects:  1, Inicialisation of the SPI interface, and the
 * 				  	 GPIO pins used by the com-r04 module
 * 				  2, Setting the Configuration setting to 433 MHz 
 * 					 main band, 12pF load and enabling Tx data register
 * 					 Rx FIFO.
 * 				  3, Setting up the sub bands to the 433.050 - 434.790 MHz
 * 					 ISM bands using the com_r04_s01__Set_Sub_Frequency.
 * 				  4, Enabling the synthesier and the oscillator in the
 * 					 power management register
 * 				  5, Setting baseband BW with com_r04_s01__Set_Baseband_BW
 * 				  6, Setting the deviation with com_r04_s01__Set_Deviation 	
 * 				  7, Setting the Relative output power with 
 * 					 com_r04_s01__Set_Relative_Output_power 	
 * 				  8, Setting the data rate with com_r04_s01__Set_Data_rate
 *
 * Overview:      Call the appropriate MCU api functions for
 * 				  PIN direction and SPI inicialisation.
 * 				  Then configurating the RF communication with the appropirate
 * 				  API functions
 *
 * Note:          USE PRE DEFINED PARAMETERS
  ********************************************************************/
void com_r04_s01__Init_433 (unsigned int sub_frequency, unsigned char baseband_bw, unsigned char deviation, unsigned char power, unsigned char data_rate);




/*********************************************************************
 * Function: 	  void com_r04_s01__Set_Sub_Frequency (unsigned int frequency)        
 *
 * PreCondition:  SPI, and GPIO inicialisation
 *     
 * Input:         unsigned int frequency: The sub frequency band for RF 
 * 					communication. Do not set operating frequency outside
 * 					the ISM bands. USE THE PRE DEFINED SUB BANDS. 
 * 					(SUB_BAND_433_1_MHz for example)
 *
 * Output:        none  
 *
 * Side Effects:  Setting the Frequency register in the IA4420.
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          Do not set operating frequency outside the ISM bands. 
 * 				  USE THE PRE DEFINED SUB BANDS. (SUB_BAND_433_1_MHz for example)
  ********************************************************************/
#define SUB_BAND_433_1_MHz	0xA4D8
#define SUB_BAND_433_2_MHz	0xA500
#define SUB_BAND_433_3_MHz	0xA528
#define SUB_BAND_433_4_MHz	0xA550
#define SUB_BAND_433_5_MHz	0xA578
#define SUB_BAND_433_6_MHz	0xA5A0
#define SUB_BAND_433_7_MHz	0xA5C8
#define SUB_BAND_433_8_MHz	0xA5F0
#define SUB_BAND_433_9_MHz	0xA618
#define SUB_BAND_434_0_MHz	0xA640
#define SUB_BAND_434_1_MHz	0xA668
#define SUB_BAND_434_2_MHz	0xA690
#define SUB_BAND_434_3_MHz	0xA6B8
#define SUB_BAND_434_4_MHz	0xA6E0
#define SUB_BAND_434_5_MHz	0xA708
#define SUB_BAND_434_6_MHz	0xA730
#define SUB_BAND_434_7_MHz	0xA758

void com_r04_s01__Set_Sub_Frequency (unsigned int frequency);




/*********************************************************************
 * Function: 	  void com_r04_s01__Set_Baseband_BW (unsigned char baseband)
 *
 * PreCondition:  SPI, and GPIO inicialisation
 *     
 * Input:         unsigned char baseband: Select the baseband BW
 * 					between 67kHz and 400 kHz
 *
 * Output:        none  
 *
 * Side Effects:  Setting the Baseband BW for receiver part and
 * 				  also setting the LNA max, VDI output, DRSSI -103 dBm
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          Use the pre defined values like BASEBAND_BW_400_kHz 
 ********************************************************************/
#define BASEBAND_BW_400_kHz		0x20
#define BASEBAND_BW_340_kHz		0x40
#define BASEBAND_BW_270_kHz		0x60
#define BASEBAND_BW_200_kHz		0x80
#define BASEBAND_BW_134_kHz		0xA0
#define BASEBAND_BW_67_kHz		0xC0

void com_r04_s01__Set_Baseband_BW (unsigned char baseband);



/*********************************************************************
 * Function: 	  void com_r04_s01__Set_Deviation (unsigned char deviation)
 *
 * PreCondition:  SPI, and GPIO inicialisation
 *     
 * Input:         unsigned char deviation: FSK deviation between 15kHz to 240 kHz 
 *
 * Output:        none  
 *
 * Side Effects:  Setting the FSK deviation between 15kHz to 240 kHz
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          Use pre defined values like FSK_DEVIATION_90_kHz
  ********************************************************************/
#define FSK_DEVIATION_15_kHz	0x00
#define FSK_DEVIATION_30_kHz	0x10
#define FSK_DEVIATION_45_kHz	0x20
#define FSK_DEVIATION_60_kHz	0x30
#define FSK_DEVIATION_75_kHz	0x40
#define FSK_DEVIATION_90_kHz	0x50
#define FSK_DEVIATION_105_kHz	0x60
#define FSK_DEVIATION_120_kHz	0x70
#define FSK_DEVIATION_135_kHz	0x80
#define FSK_DEVIATION_150_kHz	0x90
#define FSK_DEVIATION_165_kHz	0xA0
#define FSK_DEVIATION_180_kHz	0xB0
#define FSK_DEVIATION_195_kHz	0xC0
#define FSK_DEVIATION_210_kHz	0xD0
#define FSK_DEVIATION_225_kHz	0xE0
#define FSK_DEVIATION_240_kHz	0xF0

void com_r04_s01__Set_Deviation (unsigned char deviation);



/*********************************************************************
 * Function: 	  void com_r04_s01__Set_Relative_Output_power (unsigned char power)
 *
 * PreCondition:  SPI, and GPIO inicialisation
 *     
 * Input:         unsigned char power: Relative output power. The maximum is 
 * 					about 8dBm
 *
 * Output:        none  
 *
 * Side Effects:  Setting the relative output power
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          Use pre defined values like OUTPUT_POWER_MAX_minus_6dB
  ********************************************************************/
#define OUTPUT_POWER_MAX_minus_0dB	0x00
#define OUTPUT_POWER_MAX_minus_3dB	0x01
#define OUTPUT_POWER_MAX_minus_6dB	0x02
#define OUTPUT_POWER_MAX_minus_9dB	0x03
#define OUTPUT_POWER_MAX_minus_12dB	0x04
#define OUTPUT_POWER_MAX_minus_15dB	0x05
#define OUTPUT_POWER_MAX_minus_18dB	0x06
#define OUTPUT_POWER_MAX_minus_21dB	0x07

void com_r04_s01__Set_Relative_Output_power (unsigned char power);



/*********************************************************************
 * Function: 	  void com_r04_s01__Set_Data_rate (unsigned char data_rate)
 *
 * PreCondition:  SPI, and GPIO inicialisation
 *     
 * Input:         unsigned char data_rate: setting the communication data rate
 *
 * Output:        none  
 *
 * Side Effects:  Setting the data rate register
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          Use pre defined values like DATA_RATE_9600_bps
  ********************************************************************/
#define DATA_RATE_600_bps		0xC7
#define DATA_RATE_1200_bps		0xA3
#define DATA_RATE_2400_bps		0x91
#define DATA_RATE_4800_bps		0x47
#define DATA_RATE_9600_bps		0x23
#define DATA_RATE_14400_bps		0x17
#define DATA_RATE_19200_bps		0x11
#define DATA_RATE_38400_bps		0x08

void com_r04_s01__Set_Data_rate (unsigned char data_rate);



/*********************************************************************
 * Function: 	  unsigned int com_r04_s01__Read_Status (void)
 *
 * PreCondition:  SPI, and GPIO inicialisation
 *     
 * Input:         none
 *
 * Output:        The 16bit status word of the IA4420
 *
 * Side Effects:  Reading the RF chip's status
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          none
  ********************************************************************/
unsigned int com_r04_s01__Read_Status (void);



/*********************************************************************/
/*********************************************************************/
/*****************          Transmitting	          ****************/
/*********************************************************************/
/*********************************************************************/

/*********************************************************************
 * Function: 	  void com_r04_s01__Transmitter_Disable (void)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         none
 *
 * Output:        none
 *
 * Side Effects:  Disabling the transmitter. The synthesier and the oscillator
 * 				  remains enabled.
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          Always disable transmitter after sending a packet, or the
 * 				  radio remains active and sends 0-s.
  ********************************************************************/
void com_r04_s01__Transmitter_Disable (void);



/*********************************************************************
 * Function: 	  void com_r04_s01__Start_Transmitting (void)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         none
 *
 * Output:        none
 *
 * Side Effects:  Disabling and then enabling the transmitter which starts 
 * 				  transmitting the value in the TX register
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          none
  ********************************************************************/
void com_r04_s01__Start_Transmitting (void);



/*********************************************************************
 * Function: 	  void com_r04_s01__Write_Transmit_data (unsigned char d)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         unsigned char d: 8bit data to transmit
 *
 * Output:        none
 *
 * Side Effects:  Writing the data to the transmit register
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          none
  ********************************************************************/
void com_r04_s01__Write_Transmit_data (unsigned char d);



/*********************************************************************
 * Function: 	  void com_r04_s01__Send_Packet (unsigned char* buffer, unsigned short int length)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         unsigned char* buffer: pointer to the data to send
 * 				  unsigned short int length: the length of the data
 *
 * Output:        none
 *
 * Side Effects:  Sending the data using the RF link
 *
 * Overview:      1, Inicializating the Tx reg with 0xAA preamble
 * 				  2, Start the transmitting. com_r04_s01__Start_Transmitting()
 * 				  3, Sending 7 other 0xAA as preamble
 * 				  4, Sending the 0x2DD4 as syncron pattern
 * 				  5, Sending the packet length
 * 				  6, Sending the data
 * 				  7, Calculating and sending the CRC
 * 				  8, Disabling the transducer
 *
 * Note:          This function is a blocking one. After every byte send
 * 				  we are waiting for the TX register empty IT signal, and
 * 				  therefore if radio hardware error then the program 
 * 				  execution is halted.
  ********************************************************************/
void com_r04_s01__Send_Packet (unsigned char* buffer, unsigned short int length);


/*********************************************************************/
/*********************************************************************/
/*******************          Receiving	              ****************/
/*********************************************************************/
/*********************************************************************/

/*********************************************************************
 * Function: 	  void com_r04_s01__Enable_Receiver (void)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         none
 *
 * Output:        none
 *
 * Side Effects:  Enabling the receiver path by enabling the receiver and 
 * 				  baseband
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          none
  ********************************************************************/
void com_r04_s01__Enable_Receiver (void);



/*********************************************************************
 * Function: 	  com_r04_s01__Disable_Receiver (void)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         none
 *
 * Output:        none
 *
 * Side Effects:  Disabling the receiver path
 *
 * Overview:      Uses MCU api for SPI communication.
 *
 * Note:          none
  ********************************************************************/
void com_r04_s01__Disable_Receiver (void);



/*********************************************************************
 * Function: 	  void com_r04_s01__Start_Receiving (void)
 *
 * PreCondition:  com_r04_s01__Init_433, com_r04_s01__Enable_Receiver
 *     
 * Input:         none
 *
 * Output:        none
 *
 * Side Effects:  Disabling and then enabling the Synchron pattern recognition 
 *
 * Overview:      Uses MCU api for SPI communication. For configurating the
 * 				  FIFO buffer register
 *
 * Note:          After enabling the synchron pattern recognition the IA4420
 * 				  will notify us if a 0x2DD4 is received by pulling down the
 * 				  nIRQ signal. 
  ********************************************************************/
void com_r04_s01__Start_Receiving (void);


/*********************************************************************
 * Function: 	  unsigned char com_r04_s01__Read_FIFO (void)
 *
 * PreCondition:  com_r04_s01__Init_433, com_r04_s01__Enable_Receiver, 
 * 				  com_r04_s01__Start_Receiving 
 *     
 * Input:         none
 *
 * Output:        unsigned char: 8 bit data readed from the receive FIFO
 *
 * Side Effects:  Reading 8 bit data from the FIFO 
 *
 * Overview:      Uses MCU api for SPI communication for reading the FIFO
 *
 *
 * Note:          none
  ********************************************************************/
unsigned char com_r04_s01__Read_FIFO (void);



/*********************************************************************
 * Function: 	  unsigned char com_r04_s01__Receiving_Packet (unsigned char* buffer, unsigned short int* length)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         unsigned char* buffer: pointer for the incomming data
 * 				  unsigned short int* length: the maximum length of the incomming packet
 *
 * Output:        unsigned char: COM_R04_S01__ERROR if the length of the incomming packet is
 * 								 greater than unsigned short int* length parameter. Or the 
 * 								 received packet contains a CRC error.
 * 								 COM_R04_S01__NOERROR if the packet is received correctly
 * 
 * 				  unsigned short int* length: the length of the received packet
 *
 * Side Effects:  Waiting for a packet to receive
 *
 * Overview:      1, Enabling the receiver path with com_r04_s01__Enable_Receiver()
 * 				  2, Starting the synchron patter recognition with com_r04_s01__Start_Receiving()
 * 				  3, Waiting for the synchron pattern THIS IS A BLOCKING PART WITHOUT A TIME LIMIT 
 * 				  4, reading and comparing the length of the packet with the incomming length
 * 					 parameter. If the received length is greater than the specified maximum, then
 * 					 aborting the packet receive and signaling an error
 * 				  5, receiving the packet
 * 				  6, receiving and checking the CRC. If the CRC is not correct then
 * 					 aborting the packet receive and signaling an error
 * 				  7, Packed receive finished. Disabling the receiver
 *
 * Note:          This is a blocking function and waits until a packet is received 
  ********************************************************************/
unsigned char com_r04_s01__Receiving_Packet (unsigned char* buffer, unsigned short int* length);


/*********************************************************************
 * Function: 	  unsigned char com_r04_s01__Receiving_Packet_with_timeout (unsigned char* buffer, unsigned short int* length, unsigned short int timeout)
 *
 * PreCondition:  com_r04_s01__Init_433
 *     
 * Input:         unsigned char* buffer: pointer for the incomming data
 * 				  unsigned short int* length: the maximum length of the incomming packet
 *				  unsigned short int timeout: Timeout in ms. (This is not a precise timeout only an approximetry one)
 *
 * Output:        unsigned char: COM_R04_S01__ERROR if the length of the incomming packet is
 * 								 greater than unsigned short int* length parameter. Or the 
 * 								 received packet contains a CRC error.
 *								 COM_R04_S01__TIMEOUT if timeout occured
 * 								 COM_R04_S01__NOERROR if the packet is received correctly
 * 
 * 				  unsigned short int* length: the length of the received packet
 *
 * Side Effects:  Waiting for a packet to receive with time out
 *
 * Overview:      1, Enabling the receiver path with com_r04_s01__Enable_Receiver()
 * 				  2, Starting the synchron patter recognition with com_r04_s01__Start_Receiving()
 * 				  3, Waiting for the synchron pattern or timeout
 * 				  4, reading and comparing the length of the packet with the incomming length
 * 					 parameter. If the received length is greater than the specified maximum, then
 * 					 aborting the packet receive and signaling an error
 * 				  5, receiving the packet
 * 				  6, receiving and checking the CRC. If the CRC is not correct then
 * 					 aborting the packet receive and signaling an error
 * 				  7, Packed receive finished. Disabling the receiver
 *
 * Note:          This is a blocking function and waits until a packet is received or timeout.
  ********************************************************************/

unsigned char com_r04_s01__Receiving_Packet_with_timeout (unsigned char* buffer, unsigned short int* length, unsigned short int timeout);


#endif // _COM_R04_S01b_H_


